PsL Monthly 1993 December

home *** CD-ROM | disk | FTP | other *** search

/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / tools / cx.exe / CX.DOC < prev next >

Wrap

Text File | 1992-08-03 | 23.8 KB | 605 lines

Cx 1.03 - Data Compression Library July 30, 1992 !! IMPORTANT !! ---------------------------------------------------------------- CXE103.EXE and all files contained within are Copyright (c) 1990-1992 Eugene Nelson. The original file CXE103.EXE may be distributed and used freely provided the intent of such distribution/usage is for evaluating Cx for use in applications. CXE103.EXE contains an evaluation copy of the Cx Data Compression Library. Only one of the three data compression methods (Cx1) is enabled in the evaluation version. Cx Features ----------------------------------------------------------------- * Versatile buffer based programming interface. * Programmable memory requirements 16k-64k (plus buffers) when compressing. Only 5k (plus buffers) when decompressing. * Three algorithms for different compression needs (speed vs. size). * Support for many compilers and environments, with functionally identical ANSI C source code and 80x86 assembly source code available. * Optional Cyclical Redundancy Check (CRC) for error detection. Prices ----------------------------------------------------------------- Cx 1.03 Commercial Version - Includes all three compression algorithms. - Purchaser granted the right to distribute CXWIN.DLL and CXOS2.DLL for use with applications. - Purchaser granted the right to use CX.OBJ, CX.TPU and CX.MIX in applications. - $45 (US) Cx 1.03 Commercial Version + Source - Cx 1.03 Commercial Version - ANSI C source code - 80x86 assembly language source code - $95 (US) The rights described apply to Cx version 1.03. Wisconsin residents add 5% sales tax. Non-USA residents add $5 (US). Send/Payable To: Eugene Nelson 955 E. Gorham Madison, WI 53703 USA 1 Files Included ----------------------------------------------------------------- CX.DOC - This document. CX.OBJ - Cx 1.03 in OBJ format CX.TPU - Cx 1.03 for Turbo Pascal CX.MIX - Cx 1.03 for Power C CXWIN.DLL - Cx 1.03 as a Windows DLL CXWIN.LIB - Cx 1.03 import library for CXWIN.DLL CXOS2.DLL - Cx 1.03 as an OS/2 DLL CXOS2.LIB - Cx 1.03 import library for CXOS2.DLL CX.H - C interface to Cx CXF.C - C example CXF.PAS - Turbo Pascal example CXVB.BAS - Visual Basic interface to Cx CXVB.FRM - Visual Basic example form CXVB.MAK - Visual Basic example project MAKECXF.BAT - Compiles CXF.EXE (MS-DOS and Windows) MAKECXF.CMD - Compiles CXF.EXE (OS/2) WINIO.OBJ - An object file that allows C based Windows programs to emulate console programs. This data is provided courtesy of Microsoft Systems Journal, Andrew Schulman and Dave Maxey, and is available on Compuserve in the Microsoft Languages Forum (GO MSL) as files S13103.ZIP and S13155.ZIP. Performance ----------------------------------------------------------------- Cx currently supports three compression methods named Cx1, Cx2 and Cx3. Cx2 emphasizes overall performance, Cx1 emphasizes compression and decompression speed and Cx3 emphasizes compression size. The following data (sorted by size) was produced with a 286/12 MHZ computer. 2 1MB of C source files (programming language) METHOD SIZE COMPRESS TIME DECOMPRESS TIME -------------------------------------------------------- ARJ 2.30 225,254 88 16 PKZIP 1.93 228,189 41 9 LHA 2.13 250,000 111 15 ZOO 2.1 250,002 295 32 *Cx3 250,261 89 41 PKZIP 1.1 254,217 63 8 *Cx2 256,547 74 25 PAK 2.51 263,998 90 19 LHARC 1.13c 279,364 178 32 Cx1 290,816 46 12 ARC 6.02 442,441 50 27 1MB of AP wire stories (natural language, English) METHOD SIZE COMPRESS TIME DECOMPRESS TIME -------------------------------------------------------- ARJ 2.30 394,880 112 22 PKZIP 1.93 397,616 64 12 LHA 2.13 439,037 123 24 ZOO 2.1 439,039 314 50 PKZIP 1.1 442,277 80 11 *Cx3 449,041 139 63 PAK 2.51 449,366 97 22 *Cx2 460,970 115 40 LHARC 1.13c 477,308 117 44 Cx1 531,648 65 20 ARC 6.02 607,023 61 33 1MB of .EXE files (machine language) METHOD SIZE COMPRESS TIME DECOMPRESS TIME -------------------------------------------------------- ARJ 2.30 549,538 119 27 PKZIP 1.93 550,472 66 14 *Cx3 559,911 213 115 LHA 2.13 568,383 113 28 ZOO 2.1 568,385 285 51 *Cx2 572,397 131 34 PAK 2.51 588,072 106 27 PKZIP 1.1 588,959 95 12 LHARC 1.13c 592,647 140 65 Cx1 606,952 74 21 ARC 6.02 770,919 69 37 Although there are algorithms which are clearly superior to Cx, it should be apparent that Cx is competitive. Cx2 performs better than LHARC 1.13c (perhaps the most popular archiver ever made) in all measurements. Cx1 provides acceptable compression with times always in the top 3. * Not enabled in evaluation version. 3 Programming Interface ----------------------------------------------------------------- Types and Constants -------------------------------------------------------------- See file CX.H or VBCX.BAS for exact values of constants. CXINT - A 16 bit unsigned integer. CXINTSIZE - The size of CXINT (2 bytes). CXBUFF - A 32 bit pointer to a buffer. CXCALL - 32 bit (far) Pascal calling convention CX_ERR_INVALID - Error code returned by Cx routines. CX_ERR_METHOD - ... CX_ERR_BUFFSIZE - ... CX_ERR_TEMPSIZE - ... CX_METHOD1 - Identifies algorithm 1 (Cx1 above). CX_METHOD2 - Identifies algorithm 2 (Cx2 above). CX_METHOD3 - Identifies algorithm 3 (Cx3 above). CX_MAX_BUFFER - The maximum buffer size that may be compressed. Currently a little less than 64k. CX_SLOP - The amount the Cx routines may overrun compressed buffers. Currently about 300 bytes. CX_C_MINTEMP - The minimum amount of temporary memory the Cx compression routines need. Currently 16k. CX_C_MAXTEMP - The maximum amount of temporary memory the Cx compression methods can use. Currently about 64k. CX_D_MINTEMP - The minimum amount of temporary memory the Cx decompression routines need. Currently 5k. 4 CXINT CXCALL CX_COMPRESS( CXINT method, CXBUFF obuff, CXINT osize, CXBUFF ibuff, CXINT isize, CXBUFF tbuff, CXINT tsize) -------------------------------------------------------------- method - Method of data compression to use. method must be CX_METHOD1, CX_METHOD2 or CX_METHOD3. >>> THE ONLY METHOD SUPPORTED IN THE EVALUATION VERSION IS CX_METHOD1 !!! obuff - Output buffer where compressed data is to be placed. osize - Size of obuff. osize must be within the range [0..CX_MAX_BUFFER]. CX_COMPRESS must have read/write access to bytes [0..osize+CX_SLOP] in obuff. ibuff - Input buffer containing data to compress. The contents of ibuff are not modified by CX_COMPRESS. isize - Bytes of data in ibuff to compress. isize must be within the range [0..CX_MAX_BUFFER]. tbuff - A buffer that will be used by Cx for temporary storage. tsize - Size of tbuff. Cx needs at least CX_C_MINTEMP bytes of temporary storage while compressing, but can make use of up to CX_C_MAXTEMP bytes. The more temporary storage provided to Cx, the greater the potential for compression. tsize must be within the range [CX_C_MINTEMP..CX_C_MAXTEMP]. RETURN - CX_ERR_METHOD The compression method requested is invalid or unsupported in the called version of CX_COMPRESS. - CX_ERR_BUFFSIZE isize or osize is not within the range [0..CX_MAX_BUFFER]. - CX_ERR_TEMPSIZE tsize is not within the range [CX_C_MINTEMP..CX_C_MAXTEMP]. - isize The data in ibuff was not compressible. In this case, no assumptions about the contents of obuff should be made. - OTHERWISE The data in ibuff was successfully compressed to obuff. The return value is the number of compressed bytes placed in obuff. 5 CXINT CXCALL CX_DECOMPRESS( CXBUFF obuff, CXINT osize, CXBUFF ibuff, CXINT isize, CXBUFF tbuff, CXINT tsize) -------------------------------------------------------------- obuff - Output buffer where decompressed data is to be placed. osize - Size of obuff. Usually, osize will be the number of bytes that where compressed into ibuff, but osize may be smaller, allowing for partial decompression of a buffer. ibuff - Input buffer containing data compressed with Cx. The contents of ibuff are not modified by CX_DECOMPRESS. isize - Size of ibuff. CX_DECOMPRESS recognizes the end of the compressed data in ibuff by a special 'End of Data' symbol, NOT by consulting isize. isize is used to prevent CX_DECOMPRESS from crashing when the data in ibuff is invalid or corrupt. isize must be within the range [0..CX_MAX_BUFFER]. CX_DECOMPRESS must have read access to bytes [0..isize+CX_SLOP] in ibuff. tbuff - A buffer that will be used by Cx for temporary storage. tsize - Size of tbuff. tsize must be at least CX_D_MINTEMP. CX_DECOMPRESS does not need (and will not use) more than CX_D_MINTEMP bytes of temporary storage. RETURN - CX_ERR_METHOD The data in ibuff is invalid, corrupt, or was compressed with a method not supported in the called version of CX_DECOMPRESS. - CX_ERR_INVALID The data in ibuff is invalid or corrupt, and can not be completely decompressed. In this case, CX_DECOMPRESS may be called with different values of osize to find the largest amount of data that can be decompressed without an error. Note, however, that just because CX_DECOMPRESS does not return CX_ERR_INVALID does not necessarily mean the decompressed data placed in obuff is valid. It simply means that no errors where detected. This is why a checksum or CRC should be stored with compressed data to help detect errors. - CX_ERR_BUFFSIZE isize is not within the range [0..CX_MAX_BUFFER]. - CX_ERR_TEMPSIZE tsize is smaller than CX_D_MINTEMP. - OTHERWISE The data in ibuff was successfully decompressed into obuff. The return value is the number of decompressed bytes placed into obuff. 6 CXINT CXCALL CX_CRC(CXBUFF, buff, CXINT n) ----------------------------------------------------------- buff - Buffer to compute Cyclical Redundancy Check (CRC) on. n - Bytes in buff. RETURN - 16 bit CRC. Programming Notes ----------------------------------------------------------------- - When compressing, it is best to present as large a buffer as possible to Cx. 60,000 bytes of data will be compressed better when CX_COMPRESS is called once, as opposed to 6 times with 10,000 bytes. - Both CX_COMPRESS and CX_DECOMPRESS are re-entrant, and may be used in multi-tasking environments. - CX_COMPRESS and CX_DECOMPRESS use less than 256 bytes of stack space. - CX_SLOP is needed for performance reasons. Cx performs faster when it is allowed to slightly overrun buffers that will or do contain compressed data. For example: ibuff = allocate (k) bytes obuff = allocate (k+CX_SLOP) bytes <- a little bigger than k CX_COMPRESS(CX_METHOD1, obuff, k, ibuff, k, ...) ibuff = allocate(k+CX_SLOP) bytes <- a little bigger than k obuff = allocate(k) bytes CX_DECOMPRESS(obuff, k, ibuff, k, ...) - Currently, Power C users are unable to use CX.OBJ and must rely upon CX.MIX. CX.MIX is a large model only version of CX.OBJ. CX.MIX is derived from the ANSI C version of Cx, and does not have the assembly language optimizations. - CX.OBJ will work with all memory models, but it is important to make sure that calls made to Cx are correct. Far pointers to data, a far call, and the Pascal calling convention. - When speed is the primary issue, consider a checksum or no error detection instead of CX_CRC. The time needed by CX_CRC compared to CX_COMPRESS and CX_DECOMPRESS is not always insignificant. 7 The Example CXF.EXE ----------------------------------------------------------------- CXF.EXE will compress and decompress a file of any size and of any type of data. The source for cxf.exe is contained in the files: cxf.c cxf.pas These files demonstrate the suggested usage for Cx. Note the following: - A CRC is computed on the compressed buffer, NOT the original data. This allows decompression of partial buffers, without the need for an additional CRC, and has proven to be more reliable. Of course, a CRC on the original data could also be stored. - Both the size of the original data and compressed data are stored. This allows storage of incompressible data, and provides any easy way to check if the stored buffer is compressed. To compile CXF.EXE simply run the batch file MAKECXF.BAT (MAKECXF.CMD for OS/2) and follow the instructions. Low Memory Situations ----------------------------------------------------------------- As stated, it is best to present large buffers to CX_COMPRESS for maximum compression. At most, this could amount to three 64k buffers (approximate), or 192k. If this is not acceptable, the input and output buffers can be made smaller, and/or the temporary storage size reduced. As an extreme example, 8k buffers could be used for input and output with temporary storage of 16k (CX_C_MINTEMP), for a total of 32k. The only way to find an acceptable solution is to experiment with buffer sizes. It may also be helpful to pass an output buffer smaller than the input buffer when compressing in the hope that the compressed data will fit. When decompressing, there are not many alternatives because decompression is based on the original buffer sizes. Note, however, the temporary storage required when decompressing is less (5k). 8 Interfacing to CX.OBJ ----------------------------------------------------------------- The compilers tested which use CX.OBJ have simply needed to link it in. If problems arise when using a compiler that has not been tested, the following notes about CX.OBJ may be helpful: - Only one segment is used, and it has the following definition: CODE SEGMENT BYTE PUBLIC 'CODE' - All buffers passed are 32 pointers. - A far call should be placed to all routines. - The pascal calling convention is used. As an example, CX_CRC looks like: CXINT CX_CRC(CXBUFF, buff, CXINT n) { push bp mov bp,sp ... mov sp,bp pop bp retf 6 } buff is located in bytes bp[8..11] and n is located in bytes bp[6..7]. The result is returned in AX. - The direction flag is assumed to be cleared, and is returned unaltered. - The following registers and 'normal' flags may be altered: AX, BX, CX, DX, ES More Information ----------------------------------------------------------------- For further information contact the address listed above or Eugene Nelson at Compuserve ID 70662,2501. Disclaimer ----------------------------------------------------------------- Eugene Nelson hereby disclaims all warranties relating to this software, whether express or implied, including without limitation any implications of suitability for a given purpose. Eugene Nelson will not be liable for any direct, incidental, consequential or other damage resulting from the use of this software. 9 ----------------end-of-author's-documentation--------------- Software Library Information: This disk copy provided as a service of Public (software) Library We are not the authors of this program, nor are we associated with the author in any way other than as a distributor of the program in accordance with the author's terms of distribution. Please direct shareware payments and specific questions about this program to the author of the program, whose name appears elsewhere in this documentation. If you have trouble getting in touch with the author, we will do whatever we can to help you with your questions. All programs have been tested and do run. To report problems, please use the form that is in the file PROBLEM.DOC on many of our disks or in other written for- mat with screen printouts, if possible. PsL cannot debug pro- programs over the telephone, though we can answer questions. Disks in the PsL are updated monthly, so if you did not get this disk directly from the PsL, you should be aware that the files in this set may no longer be the current versions. Also, if you got this disk from another vendor and are having prob- lems, be aware that some files may have become corrupted or lost by that vendor. Get a current, working disk from PsL. For a copy of the latest monthly software library newsletter and a list of the 4,000+ disks in the library, call or write Public (software) Library P.O.Box 35705 - F Houston, TX 77235-5705 1-800-2424-PSL MC/Visa/AmEx/Discover Outside of U.S. or in Texas or for general information, Call 1-713-524-6394